<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Term Output Formats
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot060.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot057.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc155">10.4</A>&nbsp;&nbsp;Term Output Formats</H2><UL>
<LI><A HREF="umsroot061.html#toc96">Write_term and Printf</A>
<LI><A HREF="umsroot061.html#toc97">Other Term Output Predicates</A>
<LI><A HREF="umsroot061.html#toc98">Default Output Options</A>
</UL>

<A NAME="secoutputformats"></A>

<A NAME="toc96"></A>
<H3 CLASS="subsection"><A NAME="htoc156">10.4.1</A>&nbsp;&nbsp;Write_term and Printf</H3>
The way ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms are printed can be customised in a number of ways.
The most flexible predicates to print terms are
<A HREF="../bips/kernel/ioterm/write_term-3.html"><B>write_term/3</B></A><A NAME="@default609"></A>
and
<A HREF="../bips/kernel/ioterm/printf-3.html"><B>printf/3</B></A><A NAME="@default610"></A>.
They both allow all variants of term output, but the format is
specified in a different way.
<A NAME="@default611"></A>
The following figure gives an overview.
<DIV CLASS="center">
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD VALIGN=top ALIGN=left>Output Option for write_term/2,3</TD>
<TD VALIGN=top ALIGN=left>Format char for printf %..w</TD>
<TD VALIGN=top ALIGN=left>Meaning</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>as(term)		</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>do not assume any particular meaning of the printed term</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>as(clause)		</TD>
<TD VALIGN=top ALIGN=left>C</TD>
<TD VALIGN=top ALIGN=left>print the term as a clause (apply clause transformations)</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>as(goal)		</TD>
<TD VALIGN=top ALIGN=left>G</TD>
<TD VALIGN=top ALIGN=left>print the term as a goal (apply goal transformations)</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>attributes(none)	</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>do not print any variable attributes</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>attributes(pretty)	</TD>
<TD VALIGN=top ALIGN=left>m</TD>
<TD VALIGN=top ALIGN=left>print attributes using the corresponding print handlers</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>attributes(full)	</TD>
<TD VALIGN=top ALIGN=left>M</TD>
<TD VALIGN=top ALIGN=left>print the full contents of all variable attributes</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>compact(false)		</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>print extra blank space (around operators, after commas, etc.) for better readability</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>compact(true)		</TD>
<TD VALIGN=top ALIGN=left>K</TD>
<TD VALIGN=top ALIGN=left>don't print blank space unless necessary</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>depth(Max)		</TD>
<TD VALIGN=top ALIGN=left>&lt;Max&gt;</TD>
<TD VALIGN=top ALIGN=left>print the term only up to a maximum nesting depth of Max (a positive integer)</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>depth(0)		</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>observe the stream-specific or global flag 'print_depth'</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>depth(full)		</TD>
<TD VALIGN=top ALIGN=left>D</TD>
<TD VALIGN=top ALIGN=left>print the whole term (may loop when the term is cyclic!)</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>dotlists(false)		</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>write lists in square bracket notation, e.g. [a,b]</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>dotlists(true)		</TD>
<TD VALIGN=top ALIGN=left>.</TD>
<TD VALIGN=top ALIGN=left>write lists as terms with functor ./2</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>newlines(false)		</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>print newlines inside quotes as escape sequence \n</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>newlines(true)		</TD>
<TD VALIGN=top ALIGN=left>N</TD>
<TD VALIGN=top ALIGN=left>print newlines as line breaks even inside quotes</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>numbervars(false)	</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>do not treat '$VAR'/1 terms specially</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>numbervars(true)	</TD>
<TD VALIGN=top ALIGN=left>I</TD>
<TD VALIGN=top ALIGN=left>print terms of the form '$VAR'(N) as named variables: 
'$VAR'(0) is printed as A, '$VAR'(25) as Z, '$VAR'(26) as A1 and so on.
When the argument is an atom or a string, just this argument is printed.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>operators(true)		</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>obey operator declarations and print prefix/infix/postfix</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>operators(false)	</TD>
<TD VALIGN=top ALIGN=left>O</TD>
<TD VALIGN=top ALIGN=left>ignore operator declarations and print functor notation</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>portrayed(false)	</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>do not use portray/1,2</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>portrayed(true)		</TD>
<TD VALIGN=top ALIGN=left>P</TD>
<TD VALIGN=top ALIGN=left>call the user-defined predicate portray/1,2 for printing</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>quoted(false)		</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>do not print quotes around strings or atoms</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>quoted(true)		</TD>
<TD VALIGN=top ALIGN=left>Q</TD>
<TD VALIGN=top ALIGN=left>quote strings and atoms if necessary</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>transform(true)		</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>apply portray transformations (write macros)</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>transform(false)	</TD>
<TD VALIGN=top ALIGN=left>T</TD>
<TD VALIGN=top ALIGN=left>do not apply portray transformations (write macros).</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>variables(default)	</TD>
<TD VALIGN=top ALIGN=left>&nbsp;</TD>
<TD VALIGN=top ALIGN=left>print variables using their source name (if available)</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>variables(raw)		</TD>
<TD VALIGN=top ALIGN=left>v</TD>
<TD VALIGN=top ALIGN=left>print variables using a system-generated name, e.g. _123</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>variables(full)		</TD>
<TD VALIGN=top ALIGN=left>V</TD>
<TD VALIGN=top ALIGN=left>print variables using source name followed by a number, e.g. Alpha_132</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>variables(anonymous)	</TD>
<TD VALIGN=top ALIGN=left>_</TD>
<TD VALIGN=top ALIGN=left>print every variable as a simple underscore</TD>
</TR></TABLE><BR>
Overview of term output options (see write_term/3 for more details)
<A NAME="outputoptions"></A>
</DIV>
The
<A HREF="../bips/kernel/ioterm/write_term-2.html"><B>write_term/2</B></A><A NAME="@default612"></A> and
<A HREF="../bips/kernel/ioterm/write_term-3.html"><B>write_term/3</B></A><A NAME="@default613"></A>
predicates print a single ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> term and accept a list of
output options (first column in the table <A HREF="#outputoptions">10.4.1</A>).<BR>
<BR>
The
<A HREF="../bips/kernel/ioterm/printf-2.html"><B>printf/2</B></A><A NAME="@default614"></A> and
<A HREF="../bips/kernel/ioterm/printf-3.html"><B>printf/3</B></A><A NAME="@default615"></A>
predicates are similar to C's printf(3) function, but provide
additional format characters for printing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms.
<A NAME="@default616"></A>
The basic format string for printing arbitrary terms is "%w".
Additional format characters can go between % and w, according
to the second column in the table <A HREF="#outputoptions">10.4.1</A>.<BR>
<BR>
For example, the following pairs of printing goals are equivalent:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
printf("%mw",  [X])  &lt;-&gt;   write_term(X, [attributes(pretty)])
printf("%O.w", [X])  &lt;-&gt;   write_term(X, [operators(false),dotlist(true)])
printf("%5_w", [X])  &lt;-&gt;   write_term(X, [depth(5),variables(anonymous)])
</PRE></BLOCKQUOTE>
<A NAME="toc97"></A>
<H3 CLASS="subsection"><A NAME="htoc157">10.4.2</A>&nbsp;&nbsp;Other Term Output Predicates</H3>
The other term output predicates
<A HREF="../bips/kernel/ioterm/write-1.html"><B>write/1</B></A><A NAME="@default617"></A>,
<A HREF="../bips/kernel/ioterm/write-1.html"><B>writeln/1</B></A><A NAME="@default618"></A>,
<A HREF="../bips/kernel/ioterm/writeq-1.html"><B>writeq/1</B></A><A NAME="@default619"></A>,
<A HREF="../bips/kernel/ioterm/write_canonical-1.html"><B>write_canonical/1</B></A><A NAME="@default620"></A>,
<A HREF="../bips/kernel/ioterm/display-1.html"><B>display/1</B></A><A NAME="@default621"></A>,
<A HREF="../bips/kernel/ioterm/print-1.html"><B>print/1</B></A><A NAME="@default622"></A>
can all be defined in terms of write_term/2 (or, similarly
in terms of printf/2) as follows:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
write(X)   :- write_term(X, []).
writeln(X)   :- write_term(X, []), nl.
writeq(X)  :- write_term(X, [variables(raw), attributes(full),
                transform(false), quoted(true), depth(full)]).
write_canonical(X) :- write_term(X, [variables(raw), attributes(full),
                transform(false), quoted(true), depth(full),
                dotlist(true), operators(false)]).
display(X) :- write_term(X, [dotlist(true), operators(false)]).
print(X)   :- write_term(X, [portrayed(true)]).
</PRE></BLOCKQUOTE>
<A NAME="toc98"></A>
<H3 CLASS="subsection"><A NAME="htoc158">10.4.3</A>&nbsp;&nbsp;Default Output Options</H3>
It is possible to set default output options for an output stream
in order to globally affect all output to this particular stream.
The
<A HREF="../bips/kernel/iostream/set_stream_property-3.html"><B>set_stream_property/3</B></A><A NAME="@default623"></A>
predicate can be used to assign default options (in the same form as
accepted by write_term/3) to a stream.
These options will then be observed by all output predicates which do not
override the particular option.<BR>
<BR>
<HR>
<A HREF="umsroot060.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot057.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
